<?

/** Example of custom routine to be called from any form.
 *  To call this function, the similar to following fetch declaration should
 *  be placed in some form column:
 *
 *  fetch=$p.custid,eval://~/util/example_fetch.php::get_addr::custs,id,tmp
 *
 *  And that is interpreted as "get a value from field 'p.custid' in the form
 *  and pass it along with source table name ('custs'), key column names
 *  ('id') and fetch column names ('tmp') to a function 'get_addr' in file
 *  'example_fetch.php' that is located in 'util' folder under site folder.
 *
 *  The file included may be without path, as long as it is placed somewhere
 *  in the include_path search path.
 *
 *  @author Jyry Kuukkanen
 *  $Id: example_fetch.php,v 1.2 2005/03/12 17:06:58 jyry Exp $
 */

include_once("sodebug.php");
include_once("soarrayset.php");
include_once("sosqlhi.php");
include_once("dzgeneric.php");

/** A function to fetch customers address, post code and post office from
 *  two different tables and return them as one string.
 *  The most interesting code is at the end of the function where the result
 *  set is aggregated and returned.
 *  @param array $Params Input parameters. See comment below.
 *  @return soArraySet Result set to return.
 */
function get_addr($Params) {

    /* v- For debugging purposes */
    include("sodebug.inc");
    # $soDebugLevel = SOD_DET;
    # $soDebugLogFile = "/tmp/luteet.log";

    /* Params exmplained:
     * (Assuming source field 'p.custid' contained '123')
     *
     * $Params["sourcetable"] == string, table name ('custs')
     * $Params["wherecols"] == array/string, where column names ('id')
     * $Params["wheredata"] == array/string, where column values ('123')
     * $Params["fetchcols"] == array/string, source table columns ('addr')
     * $Params["targetcol"] == string, target field name ('p.custid')
     * $Params["joinstr"] == string, URL encoded string to join results
     */

    /* Get db access string */
    $dbalias = dzGetIniItem(DZIS_GENERAL, DZID_DBALIAS, "app");
    $dbaccess = dzGetIniItem($dbalias, "dbaccess", "kone");

    /* Create soDa object for db access and quick db fetch object */
    $soda = new soDa($dbaccess);
    $fetch = new soDbFetch($soda);

    /* Get customer address and post code */
    soDebug("Fetch address from table ".$Params["sourcetable"], SOD_DET);
    $fetch->setTable($Params["sourcetable"]);
    $fetch->setKey(implode(" ", $Params["wherecols"]), 
                   $Params["wheredata"]);
    $fetch->setCols("address postcode country");
    
    /* This will run:
     * "SELECT address, postcode, country FROM custs WHERE id = 123" 
     * and an array of values (0, 1, 2) is returned or an empty array for an
     * sql run error.
     */
    $c_result = $fetch->run();

    /* If the sql run above did fine, then a post office should be picked
     * by the post code from another table.
     */
    if ($c_result != NULL) {
        /* Get post office from post codes table */
        $fetch->setTable("pos10");
        $fetch->setKey("country code", array($c_result[2], $c_result[1]));
        $fetch->setCols("office");
        $po_result = $fetch->run();
    }; // if

    /* Assemble result set. Note the "#" symbol at the end of the result
     * column name. It is very important as it indicates the current row
     * in target column. */
    $result = new soArraySet();
    $result->setArrayItem($Params["fetchcols"][0]."#", 0,
                          $c_result[0]."\n".$c_result[1]."  ".
                          $po_result[0]);
    /* The result now in the 1st row (0) in column 'tmp' in the result now
     * contains similar to the below (two lines):
     * Some street name, 13
     * 12345  Very nice post office
     */

    /* Some debugging info */
    soDebug("get_addr resulted ".$result->dump(), SOD_DET);

    return $result;
};

?>